package org.cybzacg.convert.core;


import org.cybzacg.convert.context.ConversionContext;
import org.cybzacg.convert.exception.ConversionException;

/**
 * 类型转换器接口
 *
 * <p>定义了类型转换的统一接口，所有具体的转换器都需要实现此接口。
 * 使用Java 17的特性，支持泛型和函数式编程。
 *
 * <p>设计原则：
 * <ul>
 *   <li>单一职责：每个转换器负责特定类型的转换</li>
 *   <li>线程安全：所有实现都必须是线程安全的</li>
 *   <li>高性能：支持缓存和优化策略</li>
 *   <li>可扩展：支持注册自定义转换器</li>
 * </ul>
 *
 * @author cybzacg.blog
 * @version 3.0
 * @since 3.0
 */
public interface TypeConverter {

    /**
     * 获取转换器支持的主要类型
     *
     * @return 支持的类型Class对象
     */
    Class<?> getSupportedType();

    /**
     * 检查是否支持指定类型的转换
     *
     * @param targetType 目标类型
     * @return 如果支持返回true，否则返回false
     */
    boolean supports(Class<?> targetType);

    /**
     * 执行类型转换
     *
     * @param <T> 目标类型
     * @param source 源对象
     * @param targetType 目标类型
     * @param defaultValue 默认值
     * @return 转换结果
     * @throws Exception 转换失败时抛出异常
     */
    <T> T convert(Object source, Class<T> targetType, T defaultValue) throws ConversionException;

    /**
     * 执行类型转换
     *
     * @param source 源对象
     * @param targetType 目标类型
     * @return 转换结果
     * @throws Exception 转换失败时抛出异常
     */
    <T> T convert(Object source, Class<T> targetType) throws ConversionException;

    /**
     * 执行类型转换（带上下文）
     *
     * @param <T> 目标类型
     * @param source 源对象
     * @param targetType 目标类型
     * @param defaultValue 默认值
     * @param context 转换上下文
     * @return 转换结果
     * @throws Exception 转换失败时抛出异常
     */
    <T> T convert(Object source, Class<T> targetType, T defaultValue, ConversionContext context) throws ConversionException;

    /**
     * 获取转换器的优先级
     * 数值越小优先级越高
     *
     * @return 优先级数值
     */
    default int getPriority() {
        return 100;
    }

    /**
     * 获取转换器名称
     *
     * @return 转换器名称
     */
    default String getName() {
        return this.getClass().getSimpleName();
    }

    /**
     * 检查转换器是否启用
     *
     * @return 如果启用返回true，否则返回false
     */
    default boolean isEnabled() {
        return true;
    }
}
